home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / sox.zip / ST.DOC < prev    next >
Text File  |  1992-06-15  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4. ST(1)                    USER COMMANDS                      ST(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      st - Sound Tools - sound sample file and effects libraries.
  10.  
  11. SYNOPSIS
  12.      cc file.c -o file libst.a
  13.  
  14. DESCRIPTION
  15.      Sound Tools  is  a  library  of  sound  sample  file  format
  16.      readers/writers  and  sound effects processors.  Sound Tools
  17.      includes skeleton C files to assist you in writing new  for-
  18.      mats  and  effects.  The full skeleton driver, skel.c, helps
  19.      you write drivers for a new format  which  has  data  struc-
  20.      tures.  The  simple  skeleton  drivers  help you write a new
  21.      driver for raw (headerless) formats, or  for  formats  which
  22.      just  have a simple header followed by raw data.  Most sound
  23.      sample formats are fairly simple: they are just a string  of
  24.      bytes  or  words  and  are presumed to be sampled at a known
  25.      data rate.  Most of them have a short data structure at  the
  26.      beginning of the file.
  27.  
  28. INTERNALS
  29.      The Sound Tools formats and effects operate on  an  internal
  30.      buffer  format  of signed 32-bit longs.  The data processing
  31.      routines are called  with  buffers  of  these  samples,  and
  32.      buffer sizes which refer to the number of samples processed,
  33.      not the number of bytes.  File readers translate  the  input
  34.      samples to signed longs and return the number of longs read.
  35.      For example, data in linear  signed  byte  format  is  left-
  36.      shifted 24 bits.  This does cause problems in processing the
  37.      data. For example:
  38.           *obuf++ = (*ibuf++ * *ibuf++)/2;
  39.      would not mix down left and right channels  into  one  mono-
  40.      phonic channel, because the resulting samples would overflow
  41.      32 bits.  Instead, the ``avg'' effects must use:
  42.           *obuf++ = *ibuf++/2 * *ibuf++/2;
  43.      Stereo data is stored with the left and right  speaker  data
  44.      in  successive samples.  Quadraphonic data is stored in this
  45.      order: left front, right front, left rear, right rear.
  46.  
  47. FORMATS
  48.      A format is responsible for translating between sound sample
  49.      files  and an internal buffer.  The internal buffer is store
  50.      in signed longs with a  fixed  sampling  rate.   The  format
  51.      operates from two data structures: a format structure, and a
  52.      private structure.  The format structure contains a list  of
  53.      control  parameters for the sample: sampling rate, data size
  54.      (bytes, words, floats, etc.), style (unsigned, signed, loga-
  55.      rithmic),  number of sound channels.  It also contains other
  56.      state information: whether  the  sample  file  needs  to  be
  57.      byte-swapped,  whether  fseek()  will  work, its suffix, its
  58.      file stream pointer, its format  pointer,  and  the  private
  59.      structure  for  the  format  .  The  private  area is just a
  60.  
  61.  
  62.  
  63. Sun Release 4.1           Last change:                          1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ST(1)                    USER COMMANDS                      ST(1)
  71.  
  72.  
  73.  
  74.      preallocated data array for the format  to  use  however  it
  75.      wishes. It should have a defined data structure and cast the
  76.      array to that structure. See voc.c for the use of a  private
  77.      data  area.  Voc.c  has  to  track  the number of samples it
  78.      writes and when finishing, seek back to the beginning of the
  79.      file  and write it out.  The private area is not very large.
  80.      The ``echo'' effect has to malloc() a much larger  area  for
  81.      its delay line buffers.  A format has 6 routines:
  82.  
  83.      startread           Set up the format parameters, or read in
  84.                          a  data  header,  or do what needs to be
  85.                          done.
  86.  
  87.      read                Given a buffer and a length: read up  to
  88.                          that  many  samples, transform them into
  89.                          signed long integers, and copy them into
  90.                          the  buffer.   Return the number of sam-
  91.                          ples actually read.
  92.  
  93.      stopread            Do what needs to be done.
  94.  
  95.      startwrite          Set up the format parameters,  or  write
  96.                          out  a  data header, or do what needs to
  97.                          be done.
  98.  
  99.      write               Given a buffer and a length:  copy  that
  100.                          many  samples out of the buffer, convert
  101.                          them from signed longs to the  appropri-
  102.                          ate  data,  and  write them to the file.
  103.                          If it can't write out all  the  samples,
  104.                          fail.
  105.  
  106.      stopwrite           Fix up any file header, or do what needs
  107.                          to be done.
  108.  
  109. EFFECTS
  110.      An effects loop has one input and one output stream.  It has
  111.      5 routines.
  112.  
  113.      getopts             is called with a character string  argu-
  114.                          ment list for the effect.
  115.  
  116.      start               is called with the signal parameters for
  117.                          the input and output streams.
  118.  
  119.      flow                is called with  input  and  output  data
  120.                          buffers,  and  (by  reference) the input
  121.                          and output data sizes.  It processes the
  122.                          input buffer into the output buffer, and
  123.                          sets the size variables to  the  numbers
  124.                          of  samples  actually  processed.  It is
  125.                          under no obligation to fill  the  output
  126.  
  127.  
  128.  
  129. Sun Release 4.1           Last change:                          2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ST(1)                    USER COMMANDS                      ST(1)
  137.  
  138.  
  139.  
  140.                          buffer.
  141.  
  142.      drain               is called after there are no more  input
  143.                          data  samples.   If the effect wishes to
  144.                          generate more data samples it copies the
  145.                          generated  data  into a given buffer and
  146.                          returns the number of samples generated.
  147.                          If  it  fills  the  buffer,  it  will be
  148.                          called again, etc.  The echo effect uses
  149.                          this to fade away.
  150.  
  151.      stop                is called when there are no  more  input
  152.                          samples  to  process.  stop may generate
  153.                          output samples on its own.   See  echo.c
  154.                          for how to do this, and see that what it
  155.                          does is absolutely bogus.
  156.  
  157. COMMENTS
  158.      Theoretically, formats can be  used  to  manipulate  several
  159.      files  inside  one program.  Multi-sample files, for example
  160.      the download for a sampling keyboard, can be handled cleanly
  161.      with this feature.
  162.  
  163. PORTABILITY PROBLEMS
  164.      Many computers don't supply arithmetic shifting, so do  mul-
  165.      tiplies and divides instead of << and >>.  The compiler will
  166.      do the right thing if the CPU supplies arithmetic  shifting.
  167.      Do all arithmetic conversions one stage at a time.  I've had
  168.      too many problems with "obviously clean"  combinations.   In
  169.      general,  don't  worry  about  "efficiency".  The sox.c base
  170.      translator is disk-bound on any machine (other than  a  8088
  171.      PC  with an SMD disk controller). Just comment your code and
  172.      make sure it's clean and simple.  You'll find that DSP  code
  173.      is extremely painful to write as it is.
  174.  
  175. BUGS
  176.      The HCOM format is not re-entrant; it can only be used  once
  177.      in a program.  The program/library interface is pretty weak.
  178.      There's too much ad-hoc information which a program is  sup-
  179.      posed  to  gather  up.   Sound  Tools wants to be an object-
  180.      oriented dataflow architecture.  The human ear can't  really
  181.      hear  better  than  20  bits.  With an internal format of 16
  182.      bits, we will eventually destroy information  when  used  to
  183.      mix CD's.  The internal format should be 24-bit signed data.
  184.      But, with 24 bits you still have to be careful  multiplying.
  185.      Check the ``vibro'' effect for how it handles this problem.
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sun Release 4.1           Last change:                          3
  196.  
  197.  
  198.  
  199.